<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Server Programming Interface</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.2 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Server Programming"
HREF="server-programming.html"><LINK
REL="PREVIOUS"
TITLE="Environment Variables"
HREF="plpython-envar.html"><LINK
REL="NEXT"
TITLE="Interface Functions"
HREF="spi-interface.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2011-12-01T22:07:59"></HEAD
><BODY
CLASS="CHAPTER"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.2 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Environment Variables"
HREF="plpython-envar.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="server-programming.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Interface Functions"
HREF="spi-interface.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="SPI"
></A
>Chapter 43. Server Programming Interface</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>43.1. <A
HREF="spi-interface.html"
>Interface Functions</A
></DT
><DD
><DL
><DT
><A
HREF="spi-spi-connect.html"
>SPI_connect</A
>&nbsp;--&nbsp;connect a procedure to the SPI manager</DT
><DT
><A
HREF="spi-spi-finish.html"
>SPI_finish</A
>&nbsp;--&nbsp;disconnect a procedure from the SPI manager</DT
><DT
><A
HREF="spi-spi-push.html"
>SPI_push</A
>&nbsp;--&nbsp;push SPI stack to allow recursive SPI usage</DT
><DT
><A
HREF="spi-spi-pop.html"
>SPI_pop</A
>&nbsp;--&nbsp;pop SPI stack to return from recursive SPI usage</DT
><DT
><A
HREF="spi-spi-execute.html"
>SPI_execute</A
>&nbsp;--&nbsp;execute a command</DT
><DT
><A
HREF="spi-spi-exec.html"
>SPI_exec</A
>&nbsp;--&nbsp;execute a read/write command</DT
><DT
><A
HREF="spi-spi-execute-with-args.html"
>SPI_execute_with_args</A
>&nbsp;--&nbsp;execute a command with out-of-line parameters</DT
><DT
><A
HREF="spi-spi-prepare.html"
>SPI_prepare</A
>&nbsp;--&nbsp;prepare a plan for a command, without executing it yet</DT
><DT
><A
HREF="spi-spi-prepare-cursor.html"
>SPI_prepare_cursor</A
>&nbsp;--&nbsp;prepare a plan for a command, without executing it yet</DT
><DT
><A
HREF="spi-spi-prepare-params.html"
>SPI_prepare_params</A
>&nbsp;--&nbsp;prepare a plan for a command, without executing it yet</DT
><DT
><A
HREF="spi-spi-getargcount.html"
>SPI_getargcount</A
>&nbsp;--&nbsp;return the number of arguments needed by a plan
  prepared by <CODE
CLASS="FUNCTION"
>SPI_prepare</CODE
></DT
><DT
><A
HREF="spi-spi-getargtypeid.html"
>SPI_getargtypeid</A
>&nbsp;--&nbsp;return the data type OID for an argument of
  a plan prepared by <CODE
CLASS="FUNCTION"
>SPI_prepare</CODE
></DT
><DT
><A
HREF="spi-spi-is-cursor-plan.html"
>SPI_is_cursor_plan</A
>&nbsp;--&nbsp;return <TT
CLASS="SYMBOL"
>true</TT
> if a plan
  prepared by <CODE
CLASS="FUNCTION"
>SPI_prepare</CODE
> can be used with
  <CODE
CLASS="FUNCTION"
>SPI_cursor_open</CODE
></DT
><DT
><A
HREF="spi-spi-execute-plan.html"
>SPI_execute_plan</A
>&nbsp;--&nbsp;execute a plan prepared by <CODE
CLASS="FUNCTION"
>SPI_prepare</CODE
></DT
><DT
><A
HREF="spi-spi-execute-plan-with-paramlist.html"
>SPI_execute_plan_with_paramlist</A
>&nbsp;--&nbsp;execute a plan prepared by <CODE
CLASS="FUNCTION"
>SPI_prepare</CODE
></DT
><DT
><A
HREF="spi-spi-execp.html"
>SPI_execp</A
>&nbsp;--&nbsp;execute a plan in read/write mode</DT
><DT
><A
HREF="spi-spi-cursor-open.html"
>SPI_cursor_open</A
>&nbsp;--&nbsp;set up a cursor using a plan created with <CODE
CLASS="FUNCTION"
>SPI_prepare</CODE
></DT
><DT
><A
HREF="spi-spi-cursor-open-with-args.html"
>SPI_cursor_open_with_args</A
>&nbsp;--&nbsp;set up a cursor using a query and parameters</DT
><DT
><A
HREF="spi-spi-cursor-open-with-paramlist.html"
>SPI_cursor_open_with_paramlist</A
>&nbsp;--&nbsp;set up a cursor using parameters</DT
><DT
><A
HREF="spi-spi-cursor-find.html"
>SPI_cursor_find</A
>&nbsp;--&nbsp;find an existing cursor by name</DT
><DT
><A
HREF="spi-spi-cursor-fetch.html"
>SPI_cursor_fetch</A
>&nbsp;--&nbsp;fetch some rows from a cursor</DT
><DT
><A
HREF="spi-spi-cursor-move.html"
>SPI_cursor_move</A
>&nbsp;--&nbsp;move a cursor</DT
><DT
><A
HREF="spi-spi-scroll-cursor-fetch.html"
>SPI_scroll_cursor_fetch</A
>&nbsp;--&nbsp;fetch some rows from a cursor</DT
><DT
><A
HREF="spi-spi-scroll-cursor-move.html"
>SPI_scroll_cursor_move</A
>&nbsp;--&nbsp;move a cursor</DT
><DT
><A
HREF="spi-spi-cursor-close.html"
>SPI_cursor_close</A
>&nbsp;--&nbsp;close a cursor</DT
><DT
><A
HREF="spi-spi-saveplan.html"
>SPI_saveplan</A
>&nbsp;--&nbsp;save a plan</DT
></DL
></DD
><DT
>43.2. <A
HREF="spi-interface-support.html"
>Interface Support Functions</A
></DT
><DD
><DL
><DT
><A
HREF="spi-spi-fname.html"
>SPI_fname</A
>&nbsp;--&nbsp;determine the column name for the specified column number</DT
><DT
><A
HREF="spi-spi-fnumber.html"
>SPI_fnumber</A
>&nbsp;--&nbsp;determine the column number for the specified column name</DT
><DT
><A
HREF="spi-spi-getvalue.html"
>SPI_getvalue</A
>&nbsp;--&nbsp;return the string value of the specified column</DT
><DT
><A
HREF="spi-spi-getbinval.html"
>SPI_getbinval</A
>&nbsp;--&nbsp;return the binary value of the specified column</DT
><DT
><A
HREF="spi-spi-gettype.html"
>SPI_gettype</A
>&nbsp;--&nbsp;return the data type name of the specified column</DT
><DT
><A
HREF="spi-spi-gettypeid.html"
>SPI_gettypeid</A
>&nbsp;--&nbsp;return the data type <ACRONYM
CLASS="ACRONYM"
>OID</ACRONYM
> of the specified column</DT
><DT
><A
HREF="spi-spi-getrelname.html"
>SPI_getrelname</A
>&nbsp;--&nbsp;return the name of the specified relation</DT
><DT
><A
HREF="spi-spi-getnspname.html"
>SPI_getnspname</A
>&nbsp;--&nbsp;return the namespace of the specified relation</DT
></DL
></DD
><DT
>43.3. <A
HREF="spi-memory.html"
>Memory Management</A
></DT
><DD
><DL
><DT
><A
HREF="spi-spi-palloc.html"
>SPI_palloc</A
>&nbsp;--&nbsp;allocate memory in the upper executor context</DT
><DT
><A
HREF="spi-realloc.html"
>SPI_repalloc</A
>&nbsp;--&nbsp;reallocate memory in the upper executor context</DT
><DT
><A
HREF="spi-spi-pfree.html"
>SPI_pfree</A
>&nbsp;--&nbsp;free memory in the upper executor context</DT
><DT
><A
HREF="spi-spi-copytuple.html"
>SPI_copytuple</A
>&nbsp;--&nbsp;make a copy of a row in the upper executor context</DT
><DT
><A
HREF="spi-spi-returntuple.html"
>SPI_returntuple</A
>&nbsp;--&nbsp;prepare to return a tuple as a Datum</DT
><DT
><A
HREF="spi-spi-modifytuple.html"
>SPI_modifytuple</A
>&nbsp;--&nbsp;create a row by replacing selected fields of a given row</DT
><DT
><A
HREF="spi-spi-freetuple.html"
>SPI_freetuple</A
>&nbsp;--&nbsp;free a row allocated in the upper executor context</DT
><DT
><A
HREF="spi-spi-freetupletable.html"
>SPI_freetuptable</A
>&nbsp;--&nbsp;free a row set created by <CODE
CLASS="FUNCTION"
>SPI_execute</CODE
> or a similar
  function</DT
><DT
><A
HREF="spi-spi-freeplan.html"
>SPI_freeplan</A
>&nbsp;--&nbsp;free a previously saved plan</DT
></DL
></DD
><DT
>43.4. <A
HREF="spi-visibility.html"
>Visibility of Data Changes</A
></DT
><DT
>43.5. <A
HREF="spi-examples.html"
>Examples</A
></DT
></DL
></DIV
><P
>  The <I
CLASS="FIRSTTERM"
>Server Programming Interface</I
>
  (<ACRONYM
CLASS="ACRONYM"
>SPI</ACRONYM
>) gives writers of user-defined
  <ACRONYM
CLASS="ACRONYM"
>C</ACRONYM
> functions the ability to run
  <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> commands inside their functions.
  <ACRONYM
CLASS="ACRONYM"
>SPI</ACRONYM
> is a set of
  interface functions to simplify access to the parser, planner,
  and executor. <ACRONYM
CLASS="ACRONYM"
>SPI</ACRONYM
> also does some
  memory management.
 </P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>   The available procedural languages provide various means to
   execute SQL commands from procedures.  Most of these facilities are
   based on SPI, so this documentation might be of use for users
   of those languages as well.
  </P
></BLOCKQUOTE
></DIV
><P
>  To avoid misunderstanding we'll use the term <SPAN
CLASS="QUOTE"
>"function"</SPAN
>
  when we speak of <ACRONYM
CLASS="ACRONYM"
>SPI</ACRONYM
> interface functions and
  <SPAN
CLASS="QUOTE"
>"procedure"</SPAN
> for a user-defined C-function that is
  using <ACRONYM
CLASS="ACRONYM"
>SPI</ACRONYM
>.
 </P
><P
>  Note that if a command invoked via SPI fails, then control will not be
  returned to your procedure.  Rather, the
  transaction or subtransaction in which your procedure executes will be
  rolled back.  (This might seem surprising given that the SPI functions mostly
  have documented error-return conventions.  Those conventions only apply
  for errors detected within the SPI functions themselves, however.)
  It is possible to recover control after an error by establishing your own
  subtransaction surrounding SPI calls that might fail.  This is not currently
  documented because the mechanisms required are still in flux.
 </P
><P
>  <ACRONYM
CLASS="ACRONYM"
>SPI</ACRONYM
> functions return a nonnegative result on
  success (either via a returned integer value or in the global
  variable <TT
CLASS="VARNAME"
>SPI_result</TT
>, as described below).  On
  error, a negative result or <TT
CLASS="SYMBOL"
>NULL</TT
> will be returned.
 </P
><P
>  Source code files that use SPI must include the header file
  <TT
CLASS="FILENAME"
>executor/spi.h</TT
>.
 </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="plpython-envar.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="spi-interface.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Environment Variables</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="server-programming.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Interface Functions</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>